WHY are these changes introduced?

Resolves https://github.com/Shopify/storefront-renderer/issues/25943

Co-authored by @aaronrichner .

WHAT is this pull request doing?

This PR adds a decoder + helper functions that may be used to parse the trie returned by product.encodedVariantExistence and product.encodedVariantAvailability fields. (Note -- at the time of this PR, encodedVariantAvailability is not yet shipped: https://github.com/Shopify/storefront-renderer/pull/28483 and we should likely defer merging this until it does.) Both of these fields are currently intended to be shipped in the 10-2024 release.

Encoded option values enable clients to obtain a full picture of which variants exist or have availability for a product. This is especially useful for products that may have very large variant sets (increased variants, combined listings), since the amount of data required to query and generate this information on the client may be significant.

The encoding logic is identical for both encodedVariantExistence and encodedVariantAvailability.

How does option value encoding work?

The encoded string represents arrays of option value indices, structured as an encoded trie. The encoding strategy allows information about extremely large numbers of variants to be expressed in an extremely compact data structure

A value present in the encoding for encodedVariantExistence indicates that the product has a variant for that option value combination. For encodedVariantAvailability, presence indicates that the variant for the option value combination is available to be purchased. For example, a product with options [{ name: "color", values: ["red", "green'] }, { name: "size", values: ["small", "medium'] }, { name: "material", values: ["cotton", "linen'] }] may only have variants for red/small/cotton and green/medium/linen. In this case, the encodedVariantExistence string would contain (packed) entries for the following option value indices: [ [0, 0, 0], [1, 1, 1] ].

V1 of the encoding strategy below:

Integers represent option and values, so [0,3] represents option_value at array index 0 for the option at array index 0 and option_value at array index 3 for the option at array index 1.

:, ,, and - are control characters.
: indicates a new option. ex: 0:1 indicates value 0 for the option in position 1, value 1 for the option in position 2.
, indicates the end of a repeated prefix, multiple consecutive commas indicate the end of multiple repeated prefixes.
indicates a gap in the sequence of option values. ex: 0 4 indicates option values in position 0 and 4 are present.
- indicates a continuous range of option values. ex: 0 1-3 4

Encoding process for encodedVariantExistence:

Example options: [Size, Color, Material]
Example values: [[Small, Medium, Large], [Red, Blue], [Cotton, Wool]]
Existing variants: [Small, Red, Cotton] (0:0:0), [Small, Blue, Cotton] (0:1:0), [Small, Blue, Wool] (0:1:1), [Medium, Red, Cotton] (1:0:0), [Medium, Red, Wool] (1:0:1), [Medium, Blue, Wool] (1:1:1), [Large, Red, Wool] (2:0:1), [Large, Blue, Cotton] (2:1:0)
Option value indices for existing variants: [[0,0,0], [0,1,0], [0,1,1], [1,0,0], [1,0,1], [1,1,1], [2,0,1], [2,1,0]]

Step 1: Encode as string: "0:0:0,0:1:0,0:1:1,1:0:0,1:0:1,1:1:1,2:0:1,2:1:0,"
Step 2: Combine nodes that share a prefix: "0:0:0,0:1:0 1,1:0:0 1,1:1:1,2:0:1,2:1:0,"
Step 3: Encode data as a trie so no prefixes need to be repeated: "0:0:0,1:0 1,,1:0:0 1,1:1,,2:0:1,1:0,,"
Step 4: Since the options are sorted, use a dash to express ranges: "0:0:0,1:0-1,,1:0:0-1,1:1,,2:0:1,1:0,,"

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation